table of contents
NMCLI(1) | General Commands Manual | NMCLI(1) |
NAME¶
nmcli - command-line tool for controlling NetworkManager
SYNOPSIS¶
nmcli [OPTIONS...] {help | general | networking | radio | connection | device | agent | monitor} [COMMAND] [ARGUMENTS...]
DESCRIPTION¶
nmcli is a command-line tool for controlling NetworkManager and reporting network status. It can be utilized as a replacement for nm-applet or other graphical clients. nmcli is used to create, display, edit, delete, activate, and deactivate network connections, as well as control and display network device status. See nmcli-examples(7) for ready to run nmcli examples.
Typical uses include:
OPTIONS¶
-a | --ask
-c | --colors {yes | no | auto}
The actual colors used are configured as described in terminal-colors.d(5). Please refer to the COLORS section for a list of color names supported by nmcli.
If the environment variable NO_COLOR is set (to any non-empty value), then coloring is disabled with mode "auto". If the environment variable CLICOLOR_FORCE is set (to any non-empty value), then coloring is enabled with mode "auto". Explicitly enabling coloring overrides the environment variable.
--complete-args
The exit status will indicate success or return a code 65 to indicate the last argument is a file name.
NetworkManager ships with command completion support for GNU Bash.
-e | --escape {yes | no}
If omitted, default is yes.
-f | --fields {field1,field2... | all | common}
If omitted, default is common.
-g | --get-values {field1,field2... | all | common}
If a section is specified instead of a field, the section name will be printed followed by colon separated values of the fields belonging to that section, all on the same line.
-h | --help
-m | --mode {tabular | multiline}
tabular
multiline
If omitted, default is tabular for most commands. For the commands producing more structured information, that cannot be displayed on a single line, default is multiline. Currently, they are:
-p | --pretty
-s | --show-secrets
-t | --terse
--offline
The connection data format (keyfile) is described in nm-settings-keyfile(5) manual.
-v | --version
-w | --wait seconds
Specifying a value of 0 instructs nmcli not to wait but to exit immediately with a status of success. The default value depends on the executed command.
GENERAL COMMANDS¶
nmcli general {status | hostname | permissions | logging | reload} [ARGUMENTS...]
Use this command to show NetworkManager status and permissions. You can also get and change system hostname, as well as NetworkManager logging level and domains.
status
hostname [hostname]
Note that the term "system" hostname may also be referred to as "persistent" or "static" by other programs or tools. The hostname is stored in /etc/hostname file in most distributions. For example, systemd-hostnamed service uses the term "static" hostname and it only reads the /etc/hostname file when it starts.
permissions
logging [level level] [domains domains...]
reload [flags...]
conf
dns-rc
dns-full
With no flags, everything that is supported is reloaded, which is identical to sending a SIGHUP. See NetworkManager(8) for more details about signals.
NETWORKING CONTROL COMMANDS¶
nmcli networking {on | off | connectivity} [ARGUMENTS...]
Query NetworkManager networking status, enable and disable networking.
on, off
connectivity [check]
Possible states are:
none
portal
limited
full
unknown
RADIO TRANSMISSION CONTROL COMMANDS¶
nmcli radio {all | wifi | wwan} [ARGUMENTS...]
Show radio switches status, or enable and disable the switches.
wifi [on | off]
wwan [on | off]
all [on | off]
ACTIVITY MONITOR¶
nmcli monitor
Observe NetworkManager activity. Watches for changes in connectivity state, devices or connection profiles.
See also nmcli connection monitor and nmcli device monitor to watch for changes in certain devices or connections.
CONNECTION MANAGEMENT COMMANDS¶
nmcli connection {show | up | down | modify | add | edit | clone | delete | monitor | reload | load | import | export | migrate} [ARGUMENTS...]
NetworkManager stores all network configuration as "connections", which are collections of data (Layer2 details, IP addressing, etc.) that describe how to create or connect to a network. A connection is "active" when a device uses that connection's configuration to create or connect to a network. There may be multiple connections that apply to a device, but only one of them can be active on that device at any given time. The additional connections can be used to allow quick switching between different networks and configurations.
Consider a machine which is usually connected to a DHCP-enabled network, but sometimes connected to a testing network which uses static IP addressing. Instead of manually reconfiguring eth0 each time the network is changed, the settings can be saved as two connections which both apply to eth0, one for DHCP (called default) and one with the static addressing details (called testing). When connected to the DHCP-enabled network the user would run nmcli con up default , and when connected to the static network the user would run nmcli con up testing.
show [--active] [--order [+-]category:...]
The --order option can be used to get custom ordering of connections. The connections can be ordered by active status (active), name (name), type (type) or D-Bus path (path). If connections are equal according to a sort order category, an additional category can be specified. The default sorting order is equivalent to --order active:name:path. + or no prefix means sorting in ascending order (alphabetically or in numbers), - means reverse (descending) order. The category names can be abbreviated (e.g. --order -a:na).
show [--active] [id | uuid | path | apath] ID...
id, uuid, path and apath keywords can be used if ID is ambiguous. Optional ID-specifying keywords are:
id
uuid
path
apath
It is possible to filter the output using the global --fields option. Use the following values:
profile
active
You can also specify particular fields. For static configuration, use setting and property names as described in nm-settings-nmcli(5) manual page. For active data use GENERAL, IP4, DHCP4, IP6, DHCP6, VPN.
When no command is given to the nmcli connection, the default action is nmcli connection show.
up [id | uuid | path] ID [ifname ifname] [ap BSSID] [passwd-file file]
If --wait option is not specified, the default timeout will be 90 seconds.
See connection show above for the description of the ID-specifying keywords.
Available options are:
ifname
ap
passwd-file
setting_name.property_name:the password
For example, for WPA Wi-Fi with PSK, the line would be
802-11-wireless-security.psk:secret12345
For 802.1X password, the line would be
802-1x.password:my 1X password
nmcli also accepts wifi-sec and wifi strings instead of 802-11-wireless-security. When NetworkManager requires a password and it is not given, nmcli will ask for it when run with --ask. If --ask was not passed, NetworkManager can ask another secret agent that may be running (typically a GUI secret agent, such as nm-applet or gnome-shell).
down [id | uuid | path | apath] ID...
Be aware that this command deactivates the specified active connection, but the device on which the connection was active, is still ready to connect and will perform auto-activation by looking for a suitable connection that has the 'autoconnect' flag set. Note that the deactivating connection profile is internally blocked from autoconnecting again. Hence it will not autoconnect until reboot or until the user performs an action that unblocks autoconnect, like modifying the profile or explicitly activating it.
In most cases you may want to use device down command instead.
The connection is identified by its name, UUID or D-Bus path. If ID is ambiguous, a keyword id, uuid, path or apath can be used.
See connection show above for the description of the ID-specifying keywords.
If --wait option is not specified, the default timeout will be 10 seconds.
modify [--temporary] [id | uuid | path] [ID] {option value | [+|-]setting.property value}...
To set the property just specify the property name followed by the value. An empty value ("") resets the property value to the default.
See nm-settings-nmcli(5) for complete reference of setting and property names, their descriptions and default values. The setting and property can be abbreviated provided they are unique.
If you want to append an item or a flag to the existing value, use + prefix for the property name or alias. If you want to remove items from a container-type or flag property, use - prefix. For certain properties you can also remove elements by specifying the zero-based index(es). The + and - modifiers only have a real effect for properties that support them. These are for example multi-value (container) properties or flags like ipv4.dns, ip4, ipv4.addresses, bond.options, 802-1x.phase1-auth-flags etc.
The connection is identified by its name, UUID or D-Bus path. If ID is ambiguous, a keyword id, uuid or path can be used. The ID is not used with the global --offline option.
When the global --offline is used, the command reads the connection from the standard input and prints the modified connection to standard output instead of making the the NetworkManager daemon act upon specified connection.
modify [--temporary] [id | uuid | path] ID remove setting
add [save {yes | no}] {option value | [+|-]setting.property value}...
You need to describe the newly created connections with the property and value pairs. See nm-settings-nmcli(5) for the complete reference. The syntax is the same as of the nmcli connection modify command.
To construct a meaningful connection you at the very least need to set the connection.type property (or use the type alias) to one of known NetworkManager connection types:
The most typical uses are described in the EXAMPLES section.
Aside from the properties and values two special options are accepted:
save
--
When the global --offline is used, the command prints the resulting connection to standard output instead of actually adding the connection via the NetworkManager daemon.
edit {[id | uuid | path] ID | [type type] [con-name name] }
The existing connection is identified by its name, UUID or D-Bus path. If ID is ambiguous, a keyword id, uuid, or path can be used. See connection show above for the description of the ID-specifying keywords. Not providing an ID means that a new connection will be added.
The interactive editor will guide you through the connection editing and allow you to change connection parameters according to your needs by means of a simple menu-driven interface. The editor indicates what settings and properties can be modified and provides in-line help.
Available options:
type
con-name
See also nm-settings-nmcli(5) for all NetworkManager settings and property names, and their descriptions; and nmcli-examples(7) for sample editor sessions.
clone [--temporary] [id | uuid | path] ID new_name
The new connection profile will be saved as persistent unless --temporary option is specified, in which case the new profile won't exist after NetworkManager restart.
delete [id | uuid | path] ID...
If --wait option is not specified, the default timeout will be 10 seconds.
monitor [id | uuid | path] ID...
Monitors all connection profiles in case none is specified. The command terminates when all monitored connections disappear. If you want to monitor connection creation consider using the global monitor with nmcli monitor command.
reload
load filename...
import [--temporary] type type file file
Only VPN configurations are supported at the moment. The configuration is imported by NetworkManager VPN plugins. type values are the same as for vpn-type option in nmcli connection add. VPN configurations are imported by VPN plugins. Therefore the proper VPN plugin has to be installed so that nmcli could import the data.
The imported connection profile will be saved as persistent unless --temporary option is specified, in which case the new profile won't exist after NetworkManager restart.
export [id | uuid | path] ID [file]
Only VPN connections are supported at the moment. A proper VPN plugin has to be installed so that nmcli could export a connection. If no file is provided, the VPN configuration data will be printed to standard output.
migrate [--plugin plugin...] [id | uuid | path] [ID...]
The connection to be migrated is identified by its name, UUID or D-Bus path. If ID is ambiguous, a keyword id, uuid or path can be used. See connection show above for the description of the ID-specifying keywords.
If no connections are specified, the command acts on all available connections. Therefore, with no arguments, the command migrates all connection profiles to the keyfile plugin.
If --wait option is not specified, the default timeout will be 10 seconds.
DEVICE MANAGEMENT COMMANDS¶
nmcli device {status | show | set | up | connect | reapply | modify | down | disconnect | delete | monitor | wifi | lldp | checkpoint} [ARGUMENTS...]
Show and manage network interfaces.
status
This is the default action if no command is specified to nmcli device.
show [ifname]
set [ifname] ifname [autoconnect {yes | no}] [managed {yes | no}]
up ifname
If no compatible connection exists, a new profile with default settings will be created and activated. This differentiates nmcli connection up ifname "$DEVICE" from nmcli device up "$DEVICE"
If --wait option is not specified, the default timeout will be 90 seconds.
connect ifname
reapply ifname
modify ifname {option value | [+|-]setting.property value}...
This command lets you do temporary changes to a configuration active on a particular device. The changes are not preserved in the connection profile.
See nm-settings-nmcli(5) for the list of available properties. Please note that some properties can't be changed on an already connected device.
down ifname...
If --wait option is not specified, the default timeout will be 10 seconds.
disconnect ifname...
delete ifname...
If --wait option is not specified, the default timeout will be 10 seconds.
monitor [ifname...]
Monitors all devices in case no interface is specified. The monitor terminates when all specified devices disappear. If you want to monitor device addition consider using the global monitor with nmcli monitor command.
wifi [list [--rescan | auto | no | yes] [ifname ifname] [bssid BSSID]]
By default, nmcli ensures that the access point list is no older than 30 seconds and triggers a network scan if necessary. The --rescan can be used to either force or disable the scan regardless of how fresh the access point list is.
wifi connect (B)SSID [password password] [wep-key-type {key | phrase}] [ifname ifname] [bssid BSSID] [name name] [private {yes | no}] [hidden {yes | no}]
If --wait option is not specified, the default timeout will be 90 seconds.
Available options are:
password
wep-key-type
ifname
bssid
name
private
hidden
wifi hotspot [ifname ifname] [con-name name] [ssid SSID] [band {a | bg}] [channel channel] [password password]
Parameters of the hotspot can be influenced by the optional parameters:
ifname
con-name
ssid
band
channel
password
Note that --show-secrets global option can be used to print the hotspot password. It is useful especially when the password was generated.
wifi rescan [ifname ifname] [ssid SSID...]
This command does not show the APs, use nmcli device wifi list for that.
wifi show-password [ifname ifname]
lldp [list [ifname ifname]]
checkpoint [--timeout seconds] [ifname...] -- COMMAND...
This allows doing disruptive configuration changes over remote connections with an option of restoring the network configuration to a known good state in case of an error.
If the a list of interface names is specified, the checkpoint is taken, the checkpoint is takes only on the specified devices. Otherwise a checkpoint is taken for all devices.
Currently the timeout defaults to 15 seconds. This may change in a future version.
SECRET AGENT¶
nmcli agent {secret | polkit | all}
Run nmcli as a NetworkManager secret agent, or polkit agent.
secret
polkit
all
COLORS¶
Implicit coloring can be disabled by an empty file /etc/terminal-colors.d/nmcli.disable.
See terminal-colors.d(5) for more details about colorization configuration. The logical color names supported by nmcli are:
connection-activated
connection-activating
connection-disconnecting
connection-external
connection-invisible
connection-deprecated
connectivity-full
connectivity-limited
connectivity-none
connectivity-portal
connectivity-unknown
device-activated
device-activating
device-disconnected
device-external
device-firmware-missing
device-plugin-missing
device-unavailable
device-disabled
manager-running
manager-starting
manager-stopped
permission-auth
permission-no
permission-yes
prompt
state-asleep
state-connected-global
state-connected-local
state-connected-site
state-connecting
state-disconnected
state-disconnecting
wifi-signal-excellent
wifi-signal-fair
wifi-signal-good
wifi-signal-poor
wifi-signal-unknown
wifi-deprecated
disabled
enabled
ENVIRONMENT VARIABLES¶
nmcli's behavior is affected by the following environment variables.
LC_ALL
LC_MESSAGES
LANG
NO_COLOR
PAGER
Note that the pager command is expected to handle wide characters and ANSI escape sequences for changing colors (unless they're disabled). nmcli sets up the environment variables LESS and LESSCHARSET appropriately for the less(1) pager, other pagers may or may not need extra configuration.
If unspecified, pager(1), less(1) and more(1) will be tried (in that order).
TERM
Terminal types other than dumb are assumed to support ASCII escape sequences for setting the output color.
INTERNATIONALIZATION NOTES¶
Be aware that nmcli is localized and that is why the output depends on your environment. This is important to realize especially when you parse the output.
Call nmcli as LC_ALL=C nmcli to be sure the locale is set to C while executing in a script.
LC_ALL, LC_MESSAGES, LANG variables specify the LC_MESSAGES locale category (in that order), which determines the language that nmcli uses for messages. The C locale is used if none of these variables are set, and this locale uses English messages.
EXIT STATUS¶
nmcli exits with status 0 if it succeeds, a value greater than 0 is returned if an error occurs.
0
1
2
3
4
5
6
7
8
10
65
EXAMPLES¶
This section presents various examples of nmcli usage. If you want even more, please refer to nmcli-examples(7) manual page.
nmcli -t -f RUNNING general
nmcli -t -f STATE general
nmcli radio wifi off
nmcli connection show
nmcli -p -m multiline -f all con show
nmcli connection show --active
nmcli -f name,autoconnect c s
nmcli -p connection show "My default em1"
nmcli --show-secrets connection show "My Home Wi-Fi"
nmcli -f active connection show "My default em1"
nmcli -f profile con s "My wired connection"
nmcli -p con up "My wired connection" ifname eth0
nmcli con up 6b028a27-6dc9-4411-9886-e9ad1dd43761 ap 00:3A:98:7C:42:D3
nmcli device status
nmcli dev down em2
nmcli -f GENERAL,WIFI-PROPERTIES dev show wlan0
nmcli -f CONNECTIONS device show wlp3s0
nmcli dev wifi
nmcli dev wifi con "Cafe Hotspot 1" password caffeine name "My cafe"
nmcli -s dev wifi hotspot con-name QuickHotspot
nmcli dev modify em1 ipv4.method shared
nmcli dev modify em1 ipv6.address 2001:db8::a:bad:c0de
nmcli connection add type ethernet autoconnect no ifname eth0
nmcli c a ifname Maxipes-fik type vlan dev eth0 id 55
nmcli c a ifname eth0 type ethernet ipv4.method disabled ipv6.method link-local
nmcli connection edit ethernet-em1-2
nmcli connection edit type ethernet con-name "yet another Ethernet connection"
nmcli con mod ethernet-2 connection.autoconnect no
nmcli con mod "Home Wi-Fi" wifi.mtu 1350
nmcli con mod em1-1 ipv4.method manual ipv4.addr "192.168.1.23/24 192.168.1.1, 10.10.1.5/8, 10.0.0.11"
nmcli con modify ABC +ipv4.dns 8.8.8.8
nmcli con modify ABC -ipv4.addresses "192.168.100.25/24 192.168.1.1"
nmcli con import type openvpn file ~/Downloads/frootvpn.ovpn
nmcli con export corp-vpnc /home/joe/corpvpn.conf
NOTES¶
nmcli accepts abbreviations, as long as they are a unique prefix in the set of possible options. As new options get added, these abbreviations are not guaranteed to stay unique. For scripting and long term compatibility it is therefore strongly advised to spell out the full option names.
BUGS¶
There are probably some bugs. If you find a bug, please report it to your distribution or upstream at https://gitlab.freedesktop.org/NetworkManager/NetworkManager.
SEE ALSO¶
nmcli-examples(7), nm-settings-nmcli(5), nm-online(1), NetworkManager(8), NetworkManager.conf(5), nm-applet(1), nm-connection-editor(1), terminal-colors.d(5).
NetworkManager 1.46.0 |